Web Crossing/Chat
Sysop Documentation

18SEP97

10AUG97

» Features

Chat rooms work with any Java-enabled browser. A chat room is part of a normal browser page, so you can use standard HTML to place advertisements or other material around the chat area.

You can provide multiple "tables" per room or cafe, so users can table hop to find interesting places.

WebX can create overflow tables automatically, so a single table doesn't get too large (e.g. you might choose to start a new table every 50 users).

You can see a list of users at your current table, and a count of read-only lurkers.

You can send private messages to other users at your table.

You can invite other users to enter a private 1-on-1 table.

Hosts can eject obnoxious users.

Hosts can broadcast to all users in a room regardless of their table.

Access lists are part of each chat table, so you can restrict access as desired. Access rights can be host (read/write/eject/broadcast), participant (read/write), read-only, or none. Web Crossing registration/login is used to authenticate registered users. Unregistered guests can have separate access rights, and can be totally excluded if desired.

Automatic e-mail validation is available for new users. In conjunction with access lists, this allows you to control your community and to eject people if required.

User's can select their own message color to be used for displaying their messages to all users in the chat room.

Essentially unlimited number of users, depending on your license, by setting up multiple cooperating fanout servers. The design goal for chat is to run with 100,000 simultaneous users.

For a hosted auditorium-style event, each end-user can be in two chat rooms simultaneously: one (read/only) in which the guest is speaking, and one (read/write) in which they can converse and ask questions of the guest. Chat monitors in the various read/write end-user rooms forward questions to the speaker in a separate (private) chat area, from which the speaker can choose the questions to which to respond.

Java source-code for the client is available for license.

» Overview

» Rooms with one table

A room with one table

In a room with one table, users don't see the table per se. They come into the room and talk, and the table and the room merge into one place.

Sample interface with one table

The default chat room layout shows the chat messages on the left, a list of users at the table on the right, a place to type a new message below, and a pull-down menu of commands. The room layout is highly configurable to match your needs on a room-by-room basis.

The pull-down menu allows users to send private messages, ignore a bozo user, or invite someone to join them in a private room. Chat room hosts can also eject users who are not adhering to the community guidelines.

» Rooms with multiple tables

A room with multiple tables

In a room with multiple tables, a user enters the room and joins one of the tables. He or she can then table hop to check out other discussions.

Sample interface with multiple tables

In the default interface, a list of tables is shown at the top right. Clicking on a table name will move the user to that table. You can chose to configure the room without the list of tables, and users can still table-hop via the pull-down menu.

In a multiple-table room, chat hosts can broadcast messages to all of the tables.

» Architecture

The Web Crossing server accepts Web (HTTP) requests originating at the user's Web browser, and returns HTML pages for display to the user.

The Control Room manages and allocates all of the chat resources. The Web Crossing server sends user requests to enter a chat room to the Control Room, and gets back information about how the user is to connect to the room.

Fanout Servers actually handle chat room messages. A Java APPLET running on the user's machine will make a TCP/IP connection to a Fanout Server to actually enter a chat room.

» Single server model

Single server chat configuration

In this configuration, a single Web Crossing server is providing both discussion and chat services.

» Distributed server model

In a distributed environment, there is a single Control Room to manage all chat room assignments, but you can have as many Web Crossing and Fanout Servers as required:

Distributed server chat configuration

In a distributed environment, the various servers communicate through TCP/IP connections instead of through an internal communications channel. The Control Room server may still include a Web Crossing and/or a Fanout Server if desired.

Note that each server may run on a separate machine, or may run as another process on the same machine. Most Unix systems limit the number of TCP/IP connections per process to 256, in which case multiple processes are required to support more than 256 users. You specify the maximum number of TCP/IP connections for each fanout server as part of its configuration setup, so you can tailor this to your hardware and software capabilities.

The control room always places users in the same room on the same fanout server, until that fanout server reaches its TCP/IP connection limit. Then the control room connects additional fanout servers together in a ring architecture to allow more users to join that chat room.

The Control Room uses two ports, one for Web Crossing server connections and the other for Fanout Server connections.

Each Fanout Server uses two ports, one for clients to call and join a chat room, the other to accept connections from other fanout servers. You can have multiple Fanout Servers running on the same machine, as long as they each have their own unique port assignments.

Due to Java security requirements, applets must be downloaded from the same IP address that they will use to connect to their Fanout Server. So the configuration setup for each Fanout Server includes the URL to be used to download Java applets for that server, allowing you to ensure that this requirement is met.

» Communications data flow

Communications data flow

When a URL linking to a chat room is received, the Web Crossing service requests the Control Room to assign a Fanout Server for the user. The Control Room responds with the information required for the Java APPLET tag, and the Web Crossing service then constructs and returns the HTML page to enter the chat room.

The control room also tells the assigned Fanout Server about the chat client, so that when the client calls the Fanout Server the call is authorized and the user enters the correct room with the proper access rights.

On the client side, the returned page includes a Java APPLET tag. The user's Web browser will download the applet from the server and start it running. The applet then calls the Fanout Server to enter the chat room.

» Server Setup

» Single server model

After configuring this Web Crossing server to include chat services, you will see an Add Chat button in the sysop toolbar. Click this button to create a new chat room, then click on the room to enter it and chat.

» Distributed server model

Note that a chat certificate is only required on the Control Room server. All of the Fanout Servers will automatically share this certificate. (A Web Crossing discussion certificate is required on each Web Crossing server that is also providing discussion services.)

» Setup considerations

» SOCKS firewall setup

SOCKS is a protocol that allows programs inside a firewall to communicate across the firewall. Web Crossing chat fanout servers can be configured to use SOCKS to connect to chat services outside the firewall. This allows chat users to reside both inside and outside the firewall.

A typical SOCKS-enabled configuration

In this diagram, the control room connects to both fanout servers, in order to place users into the correct fanout server. The two fanout servers are connected together so that chat messages flow between them, and thus between the chat users inside and outside the firewall.

To set up chat across a firewall, you must perform the following steps:

1. Set up a Web Crossing chat environment outside of the firewall. The control room and at least one fanout server must be outside the firewall.

2. Set up a Web Crossing fanout server inside the firewall. Configure this fanout server to use SOCKS (see the general Chat Services link at the top of the Basic Chat Services sysop panel).

3. Establish chat rooms and tables as desired in the Web Crossing sites outside the firewall. These chat rooms can now be accessed from both inside and outside the firewall.

4. To let Web Crossing know which users are inside the firewall, login as sysop or host on the Web Crossing server with the chat room(s) to be accessed.
   • Create a user group named socks.
   • Add each user who may be inside the firewall to the socks group.

   Now, users in the socks group will normally enter the chat room through the SOCKS firewall. They will also have the ability to enter the chat rooms when they are at a computer outside the firewall, by clicking on the [Enter from outside the firewall] link next to each chat room. Users who are not in the socks group always enter the chat rooms from outside the firewall.

   You can manage access to the chat rooms in other ways by using the Web Crossing Template Language.

» Supporting chat clients behind port 80 firewalls

You must also configure this same server to provide direct HTTP service on port 80, so that the Java client can be downloaded from the same IP address as the chat service (required by Java security rules on the client).

Recommended settings for Web (HTTP) service is to set port to 80, and the directory for HTML files to the Images directory. This will prevent any files in the Web Crossing server directory from being served.

Also set the chat fanout client port to 80, and set the Java applet URL to pick up files directly from WBChat (assuming you've configured the base HTTP directory to be Images, as suggested above).

» Chat rooms

» Tables

» Adding a new room with a single table

After you've added a room, you just click on the room to enter it and chat. You will also see an Edit button next to the link to the room. You can click on this Edit button to change the room/table settings, including its access list. There is also a delete button at the end of the Edit Chat Room form.

Note that the Edit button only shows for hosts and the sysop. It does not show for regular users.

» Adding a room with multiple tables

Step 2. To add tables to the new room, you first need to get the unique ID of the room. You can get this from the URL used to enter or edit the chat room. For example, if you click on the Edit button, the URL you visit will look something like the following:

http://...webx?193@0.bQqbT7n7^1@.ee6b35c

Copy the chat room unique ID to the clipboard so it is available later.

Step 3. Create another room using the Add Chat button, and make its title the name of a table in the room. Click on the OK button.

Step 4. Click on the Edit button next to the table entry, paste the chat room unique ID into the Common room field, and click on the OK button at the bottom of the form.

Repeat steps 3 and 4 as often as desired.

When a user click on the link to a table, they will join the discussion in progress that table, and will be able to hop to other tables if they choose.

» Overflow tables

As overflow tables are created, users can table-hop to all of the tables, including overflow tables.

To set the overflow table count, use the Edit Chat Room form by clicking on the Edit button next to the chat room.

» Access lists

To attach an Access List to a specific chat room or table, click on the Edit button to the right of the link, then click on the Access List button at the bottom of the form and follow directions in the form.

You can also attach an access list to a folder containing multiple chat rooms and/or tables. The access list for a folder will apply to all chat rooms and tables in that folder and all nested folders. If a chat room/table has its own access list, then that access list completely overrides any containing folder's access list.

Many sites limit access to registered users. By excluding guest users, you can control membership in your community and ensure that everyone has a positive experience. Instead of setting access lists on each table or folder, you can completely exclude guest users from your site through the sysop Control Panel, using the Guest User Access form.

Through the use of the "Moderated Word List" located in the "General Settings" panel of the Web Crossing sysop control panel, moderated rooms will automatically disallow the use of any of these words on the list. Anytime a user types a "moderated" word, the message is returned to the user with a warning prepended to it. For example, if a user types "bad word", the chat server will return the following message only to the originating user: "Possible objectionable message NOT sent: "bad word" ".

» Customizing your chat room pages

In addition to customizing a chat-room page, you can use a custom template to change the Java params passed to the chat-room APPLET. These parameters control the layout and functionality of the applet. For example, you can change the foreground and background colors, the colors for private and broadcast messages, whether a list of tables is shown, etc. See the following section on Java APPLET parameters for details.

» Creating a template for a chat room

Step 1. Use any text editor to open the standard.tpl file included in your Web Crossing installation. This file is normally in the same directory as the Web Crossing program and its webx.db database file.

Step 2. Locate the default chatRoom template. Copy the entire template, everything from opening %% macro chatRoom %% through closing %% endmacro %% to the clipboard:

%% macro chatRoom %%
<HTML><HEAD>...
%% footer %%</BODY></HTML>%% endmacro %%

Step 3. If you haven't already done so, create a simple text file named webx.tpl. This file must be in the same directory as your Web Crossing webx.db database file.

Open the webx.tpl file and paste the default chatRoom template macro at the end of the file. Do not remove anything preceeding that might already be in an existing file.

Step 4. Rename the chatRoom template to a unique name, starting with a letter and without any spaces, such as:

%% macro HobbiesRoom %%

%% if enterRoom %%
  <applet codebase="%% roomCodebase %%" code=WBChat
    archive=WBChat.zip width=460 height=250>  <param name=handle value=%% roomHandle %%>  <param name=ip value=%% roomIp %%>  ...
  </applet>%% else %%
  <b>Could not enter the chat room:  </b>%% roomError %%
%% endif %%

Make sure you leave this section in your template macro, although you can change the APPLET attributes and params.

Step 6. Save the webx.tpl file.

Step 7. Login to Web Crossing as the sysop, go to the sysop Control Panel, and chose the Reset file cache for HTML files and webx.tpl templates command near the end of the panel. This tells Web Crossing to pick up the changes you just made to your webx.tpl file.

Step 8. Go to the chat room you want to customize, click on the Edit button next to it, enter the name of the template macro into its Template field (e.g. HobbiesRoom from the example in Step 4), and click on the OK button at the end of the form.

Step 9. Enter the chat room to check out the template. Repeat steps 5, 6, 7 as required.

» Java APPLET parameters

<param name=font value=Times>

Java parameters have the format

<param name=paramName
value=paramValue>

If the built-in parameters are not adequate, a source-code license for the Web Crossing Java client is available.

» Hosted events

To run a hosted event in Web Crossing, you need to create three chat tables:

Each member of the audience is in two tables: the host table (as read/only), and an audience table (as read/write).

Each chat host is in two tables: the audience table, and the backstage table. Actually, as audience tables overflow, each chat monitors may have multiple overflow tables up, scanning them all for messages to pass to the host. Chat monitors can also broadcast messages to the audience tables as desired.

To set up pages with multiple tables in them, see the Customizing your chat room section. To the standard chat room template, you need to add additional tables. For each table, use a section as follows:

%% setPath .xxxx %%
%% if enterRoom %%
  ...
%% endif %%

» Recording and Playback

You can set up a chat table to playback a recording on either a one-time or continuous loopback basis. Use the Playback fields in the Edit Chat Room form.

» Special Host Commands

These commands are typed into the message window of a host user just like a normal message.
1) Display a graphic image over the top of the chat message area effectively "closing" the chat session down for all users in the room. This is useful for telling users about upcoming interviews, or shutting down the session for maintenance, advertising, etc.

Command: ))g URL
Example: ))g http://www.lundeen.com/Images/webxlogo.gif
NOTE: This must be a FULL URL to a graphic image (.gif or .jpeg) which resides on the same server as the WBChat applet due to Java security restrictions.

Command: ))g
Example: ))g
NOTE: This clears the previously drawn graphic and "reopens" the chat message area.

2) Display another URL into a pre-defined frame. This allows for dynamically changing content around the chat applet.

Command: ))f framename URL
Example: ))f bottom http://www.lundeen.com/
NOTE: This must be a FULL URL to a WWW resource (.html, .gif or .jpeg, etc.).

3) Clear the commands that have been entered. Each command that is entered is saved and as new users enter the room, they are played back to keep newcomers current. To clear the commands enter the following:

Command: /d clearCommandList
Example: /d clearCommandList

4) Begin session level logging of this client.

Command: /d logSession
Example: /d logSession

» Chat status

Note that in a multiple-table room, the status panel just shows initial entry counts, not current usage after any table hopping.

» E-mail validation for new users

With e-mail validation turned on, new users are marked as provisional and an e-mail message is sent to them. A user confirms his/her address by replying to the message. Upon receipt of the reply, Web Crossing upgrades the user to have the full access rights of a registered user.

You can enable this feature through the sysop Register user access panel. The content and layout of the e-mail validation message can be specified by you.

If you enable this feature, you must regularly check the logEmail file, in the same directory as the webx.db database, for any problems that need to be handled manually.

In conjunction with automatic e-mail validation, you can specify a list of e-mail addresses or domains that are not allowed register. This allows you to eject disruptive users and keep them out permanently and automatically (until they get a new e-mail address). To permanently eject someone with a specific e-mail address, use the List of e-mail addresses that cannot auto-register setting at the end of the Registered user access panel.

» Performance testing and tuning

The methodology is to run additional copies of Web Crossing on other machines in your network or on the Internet. Each of these additional copies can be instructed to emulate actual users, with each of the emulated users periodically sending messages and table hopping. While these emulated users are running, you can enter the same chat room and confirm that it is responsive.

To start running emulated users, you need to configure a Port for direct database access in the sysop General Settings panel on the control room Web Crossing server. This direct-access service is called by each test user to enter the chat room.

Then send the following URL to your test Web Crossing servers:

...webx?200@sysop:password@.xxxx@6-nn-webxIp-webxPort-.table
  -startMin-runMin-shutdownMin-messageSecs-hopSecs

where

For example:

...webx?200@sysop:pw@.ee6b339@6-1-38.8.21.2-5000-.ee6b345-1-5-1-3-60

will start one test user, calls the control room at 38.8.21.2:5000 to get the room setup, enters the <.ee6b345> table, starts within a 1 minute interval, runs for 5 minutes, shuts down within one minute of the 5 minute run interval, sends a message every 3 seconds on average, and table hops every 60 seconds on average.

You can send multiple test user URLs to the same test server, and each set of users will run simultaneously.

To shut down all test users, send the following URL to each test server:

...webx?200@sysop:password@.xxxx@7

There are 2 known limitations under Windows or Macintosh (but not on Unix):

As a result of these two limits, you may well see in the status panel that not all the users you were expecting actually arrived. (The log file will indicate what happened to each test user, and will also tell the number of messages sent and table hops taken.)

You may want to add 50 to 100 users at a time with a very long run time and see how the server load looks. You can add more users on the user test server(s) as often as you like, and the prior ones will continue to run.

» Chat protocol

The protocol documented below for the chat rooms is public domain, but is subject to change without notice.

Client to --> Server
--> intHandle
        [One time only] Send client handle number (an integer) to server for
        initial connection. The handle is assigned by the chat server at the
        time the HTML page for the Java client applet is generated.

--> n username
        (Name) Set new name for this user. Note that this command is
        ignored if the user is not allowed to change names at the server. Note
        that at signs (@) are removed from the name by the server.

--> m message
        (Message) Broadcasts the message to all other users in the chat room.
        The server will add the sender's name (see following
        server-->client "m" command).

--> p users@message
        (Private message) Send "message" to a list of user handles, comma
        delimited.  For example, "p 12,53,2@Hi everyone" will send "Hi everyone" to
        users 2, 12, and 53.

--> c table
        (Change tables) Request the server to move the client to a different
        table.  "table" is the handle of the new table.  The server will
        respond with a "c..." message on completion.

--> l text
        (Log) If the server's log file is turned on, then log the text.
        This may be used to forward any desired information from the client
        to the server for later analysis.

--> e user@minutes@message
        (Eject) Request that the specified user handle be ejected (by
        checking IP addresses) for some number of minutes.  The message will
        be sent to the ejected user prior to ejection.

--> b message
        (Broadcast) Request a broadcast of the message to all tables for which
        this client-user is a host.

--> d command, param1, param2, ...
        (Do Server Command) Sends a command with parameters to the server for
        execution there.  Commands depend on their particular parameters and this
        is extensible.
      --  clearCommandList  
          Clear all of the stored frame change commands from the server.
      --  logSession 
          Begin Session level logging for this connection on the server

    --- Private rooms ---
    Each user has their own private table to which they may invite other users.
    This private table has the same unique handle as the user.  Inviting
    another user to a private table adds the table to that user's participant
    access list.
    If the user rejects the invitation, the table is automatically removed from
    their access list.  Otherwise, the table is removed from another user's
    access list when the originator sends an "r c" to that user.

--> r i resph@message
        (private Room Invite, originator --> server)
        Invite a responding user to enter a private room.
        "resph" is the handle of the invited (responding) user.

--> r c userh@message
        (private Room Cancel, originator or responding --> server)
        Cancel a private room.

--> r a origh@message
        (private Room Accept, responding --> server)
        Accept an invitation from an originating user to enter a private room.
        "origh" is the handle of the originating user.

--> r r origh@message
        (private Room Reject, responding --> server)
        Reject an invitation from an originating user to enter a private room

--> s
        (Stop) Close the connection to the client. (Allows graceful close.)


Client from <-- Server
A user handle "h" is a unique integer identifier.
This ID is unique over the lifetime of the server.

<-- e errNum
        Error number from the server
          ClientErrNone = 0,
          ClientErrBadHandleNonNum  = 1  Bad handle: non-numeric handle value
          ClientErrBadHandleInUse   = 2  Bad handle: handle already in use
          ClientErrBadHandleTooSmall= 3  Bad handle: no allocation, and less than the max handle seen from the control room
          ClientErrNoAllocate       = 4  Handle not obviously bad, but no allocation from the server before timing out

<-- m username@message
        (Message) A "message" from "username"

<-- x username@message
        (Moderated (x) Message) A "message" from "username".  Uses the same format as message
        but can be localized with an error message to the user.  This message is only sent
        to the originator, not to all people in the room.  This message is only sent if the
        user sent a word that is on the "Moderated Word" list located in the Sysop Control panel.

<-- b username@message
        (Broadcast) A broadcast "message" from "username"

<-- p users@message
        (Private message) A private message to a list of user handles.
        The first user handle in the list is the originator of the message.
        For example, "p 52,12@Hi There" is a private message to this
        client (which must be handle 12) from the user with handle 52.

<-- n username@h
        (reName) Install a new name for a user with handle "h"

<-- i username@h
        (In) A new user with handle "h" has joined the table

<-- o username@h
        (Out) An existing user with handle "h" has left the table

<-- l nn
        (Lurkers) Specifies the number of read-only lurkers at the table.
        "nn" can be a number to set the absolute number of lurkers, or
        "+add" or "-subtract" to adjust the number.  E.g. "23" sets the number
        of lurkers to 23; "+2" adds two lurkers; "-5" removes 5 lurkers.

<-- c table
        (Change table) Specifies the "table" handle of the new table for
        this client.  The client must reset its member list to empty and its
        lurkers count to 0.  The server will immediately follow this message
        with a new member list and lurker count.

<-- c /
        (End of change table member list).  Sent after all existing members at
        a table have been sent as "i..." commands.  This allows the client
        to recognize new entries and exits and alert the user.

<-- t th@s@tname
        (Table info) A table available to this user.
        "th" is the handle of the table, a positive unique integer.
        "s" is "h" (host), "p" (participant), "l" (lurker), "u"
        (user private table), or "0" (table has been closed).
        "tname" is the name of the table

<-- r i origh@message
        (private Room Invite server --> responding user)
        Forward a request to enter a private room from the originating
        user to the responding user.  This message will never be sent
        while the responding user is considering a previous invitation --
        the 2nd invitation will be rejected by the server with a
        canned rejection message.

<-- r c otherh@message
        (private Room Cancel server --> originating or responding user)
        Cancel a private room.

<-- r a resph@message
        (private Room Accepted server --> originating user)
        Notifies the originating user that the responder has accepted the
        invitation and is now in the private room.

<-- r r resph@message
        (private Room Rejected server --> originating user)
        Notifies the originating user that the responder has rejected the
        invitation.